This program is 'FreeWare' and must not be copied to make a profit. This means that individuals, Public Domain libraries and Disc magazines may distribute DigitalCD as long as they charge no more than required by the distribution costs (disc, postage, ...).
You may not distribute modified versions of this program and the program must be distributed as a whole. You are not allowed to use bits of it in your own programs.
This program is supplied as is, and no liability can be accepted for damage or loss resulting from the use or misuse of the software.
Introduction
============
DigitalCD is a desktop music player compatible with RISC OS 3.1 or later (including StrongArm). It provides independent control panels for any connected CD drive and music files playlists.
To a music file, open the 'Music Files' control panel from the icon bar menu or click SELECT on the icon bar, then drop the file to play on it. Music files currently supported are: Digital Symphonies (&10B), Protrackers (&CB6), Matrix (&00B), ScreamTrackers (&C02), FastTrackers (&C03)
and a few ImpulseTrackers (&C04).
To create a playlist, select 'Playlists' from the icon bar menu. From the Playlists window menu select 'New', an empty playlist will appear. Finally, drop the files to play on it, or even better, drop a directory on it, all the supported music files in it and subdirectories will be added to the playlist.
To play files from the playlist, set the 'Music Files' control panel in Program mode and start playing.
To play a CD, open the corresponding control panel from the icon bar menu or in the case of CD drive 0 click ADJUST on the icon bar.
DigitalCD supports interactive help. To make use of this feature, load the Help application supplied with your computer, or an alternative Help provider such as Bubble Help. Making use of this feature (which works on menus as well) should help you to work out what everything does if you can't guess.
I have tried to render the program as straightforward as possible in use and I have put as much information as possible in the interactive help, so use it! Should you encounter troubles, then read the rest of this help file.
The Control Panels
==================
Here follows a description of a control panel from top to bottom and
from left to right.
1) The Title Bar contains two lines of text. The first one will display, when relevant, the author and title of the track list. The second one displays the title of the current track.
2) The Track Counter shows the track that is currently played. Clicking on the counter will open a list from which a new track can be chosen.
3) The Timer has four available modes: elapsed time, remaining time, total elapsed time and total remaining time. The first two modes refer to timings within the current track, while the second two refer to timings for the whole list of tracks. Clicking SELECT or ADJUST on the timer will allow you to cycle within the four modes.
When are playing music files the timer will only display a pseudo time based on the current pattern and event. I did it because it was easier for me to use the same code for CDs and music files, but in the end it's a good thing. First, important changes in the music often occur on the start of a new pattern, so with a pattern display you start expect these changes. Next, according to playing speed changes and other subtle effects, you will experience that time is relative and that sometimes you can even travel back in time. ;-)
4) The Position Bar is a graphical representation of the current position within the track. You can click on the bar to move to a given position within the track.
5) The Volume Slider will allow you to alter the loudness of the played tracks by dragging it up or down.
Important Note:
When playing music files you can also edit the properties of the track and specify a volume in percents of this main volume. I can only recommend you set the main volume to an adequate value, then for each track in the playlist only alter the relative volume. This will ensure that once the playlist is saved you will not need anymore to fiddle with the volume slider on each track change.
6) The Mode Switches alters the way tracks are played. By clicking with SELECT or ADJUST, you can cycle within the possible values of each of the following switches:
+ Repeat has four modes:
- play track list,
- loop on track list,
- loop on current track and
- play a single track (useful when you think:
Ok, It's nearly time to leave,
I will stop when this one is played).
+ Intro scan:
when set, will only play the start of the tracks, allowing you to search a given track. The time spend on each track can be altered from within the choices window.
+ Shuffle:
when set, will play the tracks in random order.
+ Program:
when set, will play the tracks which belongs to the preference list of the current CD or the tracks from a music files playlist.
7) The Custom Area
The content his section depends on the type of player.
For a CD player there is a single icon that opens the CD Database window.
For the Music file player four icons are shown to:
+ remove the current track from the playlist,
+ delete (after confirmation) the music file corresponding to the current track,
+ edit the properties of the current track or
+ open the current playlist.
8) The Main Buttons
+ Play allows you to:
- start playback,
- restart the current track or
- resume playback on a paused track.
+ Pause allows you to:
- pause playback or
- resume playback on a paused track.
+ Stop allows you to stop playback.
9) The Move Buttons
+ Rewind allows you to move back within the current track,
+ Forward allows you to move forward within the current track,
+ Previous allows you to move to the previous track and
+ Next allows you to move to the next track.
The Music Files Playlist windows
================================
On top of the window you will find from left to right the usual content of a save box: icon for dragging, filename entry box and save button.
Below the icons you will find a list of music files, this is where you will have to drop the files or directories you want to play. The list can be managed either by the mouse or by the keyboard.
Mouse operations:
-----------------
Click with ADJUST on the window if the window does not have the focus,
will set the focus to the last item which owned the focus.
Click/drag with SELECT on an unselected item will clear any previous selection and start the selection of a range of items.
Click/drag with ADJUST will preserve the current selection and invert the selection status of a range of items.
Click/drag with SELECT on a selected item will start dragging the current selection. You will be able to drag the selection to a filer, another application, the 'Playlists' window where it will create a new playlist,
this playlist where a ghost caret will show you the destination of your
move (copy if shift is pressed), or another playlist where a ghost caret will show you the destination of your copy (move if shift is pressed).
Click with ADJUST on a list which as not the focus sets the focus to that list
without altering the current selection.
Several additional commands are provided by clicking MENU on the list:
+ Validate will remove from the list any file which have an invalid path. This is useful for removing deleted files from the list.
+ Properties will allow you to edit the properties of the currently selected item.
+ Delete Files will allow you to remove the currently selected items from the playlist and delete (after confirmation) the corresponding files.
+ Standard Cut, Copy and Paste commands (Global Clipboard is supported).
+ Select All and Clear commands.
Keyboard operations:
--------------------
Usual actions on [shift][ctrl] arrow, page up, page down
- Ctrl + A selects all items
- Ctrl + Z clears all items
- Ctrl + C copy the selection to the clipboard
- Ctrl + V inserts the clipboard content before item which has the focus
- Ctrl + X copy the selection to the clipboard, then deletes the selection
- Del deletes the selection (no use of the clipboard)
- Ins toggles follow mode on/off (use the arrows and you will understand).
- Shift + Ins starts/ends a selection of an area.
- Ctrl + Ins starts/ends an inversion of an area.
Playlist File Format:
---------------------
The file format is purely textual and can be edited by hand if required (e.g. you moved your files to another drive or directory).
To keep file sizes as small as possible a mechanism of current path is used and the following algorithm is used to read the file:
cur_path = ""
while more lines to read
read line
if line is dot terminated (line is a path)
cur_path = line
else (line is in format <file> or <file>*<options>)
This window allows you to manage playlists: from this window you can create a new playlist, remove existing playlists (closing the playlist window does not remove the document from memory, it only hides it from view) and finally choose the playlist from which the 'Music Files' control panel will extract the files to play.
The CD Database
===============
DigitalCD stores the identifier (the one returned by WhichDisc) of each CD it plays. From this window you can browse through the identifiers and assign the name of an author and a title to the CD and to each track of the CD. A Preference List window can also be opened to define an alternative sequence for playing the tracks of the CD.
The Preference List
===================
The preference list window is used to define an alternative sequence for playing the tracks of a CD. This sequence will be used when the CD control panel is in Program mode.
The window contains two list: on the left the preference list and on the right the list of tracks available on the CD.
From the right list you can select tracks and drop them at the desired position in the preference list.
From the preference list you can move/copy/delete tracks, clear the list or initialise it to reflect the list of available tracks. The tracks in this list can be mixed in any order and any track may inserted several times in the list.
Your changes will only be taken into account when the Save button is pressed in the CD Database window.
Choices
=======
1) Startup options
Restore open windows will ensure that DigitalCD stores the position of open windows before quitting the application so that when the application is restarted these windows will be reopened at the position where you leaved them.
Load playlist allows DigitalCD to load a default playlist at startup (unless the application is started by double clicking on a playlist). To specify the filename of the default playlist, type its name in the entry box or drop its icon onto it.
2) Players
+ Use filename as track title will prevent DigitalCD from using the title of the music files in the playlists and in the player title bar. Instead the leafname of the file will be used.
+ CDFS version with 150 frames bug
On some versions of CDFS (or CDFSSoftAtapi?) there is a bug in the code which is responsible for a 150 frames (2 seconds) difference between the value you specify to the CD interface to move to a given position on the disc and the value returned when asking the current position on the CD.
Is the problem present on your machine? Well, start playing a CD and use the Rewind and Forward buttons they should normally move you 1 second backward or forward in the track. If you experience something as the Forward button moving you backward in the track, turn the switch on.
+ The Sample rate is the time interval at which the players feeds the sound hardware with sound sample information. The smaller the interval is, the higher the output frequency will be. 24µs will give 41600Hz (CD quality), which is the value I used even on my old A310, and which I recommend. Should you experience problems then turn it down to 48µs (20000Hz).
+ Intro scan length is the number of seconds players configured in Intro Scan mode will play a track before moving to the next track. The default is 15 secs.
Accepted FileTypes
==================
Inside the !DigitalCD directory you will find a file called Setup and in this file a section [FileTypes]. On startup the application scans this section for lines in the form:
filetype = loader1, loader2, ...
where filetype is a RISCOS filetype, loader1 the first player that will attempt to play the file, loader2 the second one if the first refuses, etc.
For example CB6 = tim, qtm tells DigitalCD to accept filetype CB6 and play such files with the TimPlayer module, or with QTM if TimPlayer refuses.
For a complete list of loaders, see just below in the Credits.
